PrizmDoc v12.4 - Updated
Viewing Sessions
API Reference > PrizmDoc Server RESTful API > Viewing Sessions

To initiate a view, the following RESTful operations should be performed as detailed in the PrizmDoc Server Sample discussion.

GET ViewingSession

Returns the metadata associated with a valid, active viewing session. The properties returned will be those provided in the POST request that created the viewing session.

Http Method

GET

Resource URL

/PCCIS/V1/ViewingSession/u{ViewingSessionID}

Parameters

None

Request Body

None

Response Body

If successful, this method returns the same properties and values set in the body of the POST request that created the viewing session. Additionally, the following property is included in the response:

Property Name Value Description
creationTime String A UTC-formatted time string representing the moment the viewing session was created.

Example
Copy Code 
GET http://localhost:18681/PCCIS/V1/ViewingSession/uGcIsIsEGbLV2_V9yy4NzmK2HB-JuLOH--A9sZ16cla9txO0ZDBGfq1G4kKu0r_GyEps4wWCvDwn4dpnZAR76Uw

Example Response
Copy Code 
HTTP 200
Content-Type: application/json
{
  "origin": {},
  "render": {
    "flash": {
      "optimizationLevel": 1
    },
    "html5": {
      "alwaysUseRaster": false,
      "rasterResolution": 150
    }
  },
  "password": null,
  "watermarkText": null,
  "externalId": null,
  "attachmentIndex": 0,
  "attachmentDisplayName": null,
  "tenantId": null,
  "creationTime": "2015-10-14T11:55:32.6521255Z",
  "countOfInitialPages": 0,
  "documentSource": null,
  "documentExtension": "help",
  "serverCaching": "full",
  "startConverting": null,
  "contentType": null,
  "pageContentEncryption": null,
  "watermarks": []
}

The "flash.optimizationLevel" property is kept for backward compatibility with PrizmDoc versions prior to v12.0.

 

POST ViewingSession

The first step for viewing a document is to request a viewing session Identification JSON string. The body of the request is to send useful information about the document to the PrizmDoc Server which helps identify the document that will be uploaded to the service for conversion to a web compatible viewing format. The object to be posted here is the ViewSessionProperties resource which contains several properties.  

The origin property is a key pair dictionary to contain any useful arbitrary data about the document. The PrizmDoc Server sample uses ipAddress, hostname, and sourceDocument for identification purposes, but any arbitrary data can be used that helps identify or characterizes the document.  

The render property is important for storing information for client-side rendering. It stores rendering information for the HTML5 Viewer. The Html5RenderProperties class object has properties to control aspects of SVG creation.

The externalId property and tenantId should also be set. Typically, the externalId is a unique value which makes it easier to connect items in the server log to that which is in the caller’s log but is not used for any particular purpose and the same goes for tenantId. Please look at the PrizmDoc Server sample for more information on using this RESTful API.

Http Method

POST

Resource URL

/PCCIS/V1/ViewingSession

Parameters

None

Request Body

In the request body, supply a ViewingSessionProperties resource with the following optional properties:

Property Name

Value

Description

origin

List

A list of key-value pairs containing user-specific data. This is useful for tracking information pertinent to the request, like IP address, Host Name, and any other useful bits of information.

render

Nested Object

The object that describes rendering options.

render.flash

Nested Object

Deprecated. Setting this object no longer has any effect.

render.flash.optimizationLevel

Integer

Deprecated. Setting this property no longer has any effect.

render.html5

Nested Object

The object that describes rendering options for the Viewer.

render.html5.alwaysUseRaster

Boolean

Forces PrizmDoc Server to always provide raster image data to the Viewer instead of SVG, even if the Viewer supports viewing SVG data.

render.html5.rasterResolution

Integer

Deprecated. Setting this property no longer has any effect.
render.html5.svgMaxImageSize Number

For source documents which contain images, ensures that the images in the SVG delivered to the browser do not exceed a particular pixel width and/or height. For example, a value of 8000 would ensure that any images in a PDF whose width or height were greater than 8000 pixels would be down-sampled before the image was added to the final SVG. A typical value is 8000.

The default value for this property is configurable. The out-of-box configuration uses a default value of 8000.

Use 0 to disable the optimization.
render.html5.vectorTolerance Number

For CAD documents, controls how much path simplification is allowed. The path simplification algorithm will merge points which are "close together" to create an optimized SVG. You can think of this value as defining what "close together" means. A typical value is 0.3. Higher values introduce more simplification, but also more distortion. The value cannot be greater than 10.0.

The default value for this property is configurable. The out-of-box configuration uses a default value of 0.3.

Use 0 to disable the optimization.

password

String

Specifies the password to open password-protected PDF documents.

serverCaching

String

This optional property determines whether or not the conversion output is cached for potential reuse by other viewing sessions. Valid values are:

  • "full" means that the output will be cached on the server. (default)
  • "none" means that the output will not be cached on the server.

By default, the output of the document conversion process is cached on the server for potential reuse in future viewing sessions created to view the same document. This assumes that a document is likely to be viewed multiple times across different viewing sessions. If this is not the case (e.g., a new viewing session is always a new document), you can save disk space on the server by explicitly setting the serverCaching property to "none" to prevent the caching of the output on the server.

watermarkText

String

Deprecated. Setting this property no longer has any effect.

externalId

String

If the documentSource property is set to "api", empty, or is null, this property is not used by PrizmDoc Server and can be used to store a value of your choosing for the viewing session. This value could be useful for identifying requests in PrizmDoc Server log files or other purposes you find useful.

If the documentSource property is set to "http" or "file", then this property must define the URL or local file path of the source document that PrizmDoc Server will retrieve. See the How to Transfer Your Document to PrizmDoc Server topic for more details. 

tenantId

String

This is an ID for a tenant. Tenants are not a formal concept in this system and should be monitored and maintained in the calling system. However, having this data available will allow some optional behavior. For example, with this information, it would be possible to ensure some level of isolation between tenants.

attachmentIndex

Integer

Used for documents with attachment documents, like .MSG and .EML types. Otherwise, this value will typically be 0 for other document types.

attachmentDisplayName

String

Used for documents with attachment documents, like .MSG and .EML types. Provides the display name of the attachment.

countOfInitialPages

Integer

The default value is 0, which will cause PrizmDoc Server to behave in its default manner converting all pages (running enterprise=3) of the document as soon as any page is requested. Setting countOfInitialPages to a value greater than 0 will instruct PrizmDoc Server to use two separate enterprise=3 operations: one to convert pages 0 through n-1 (where "n" the supplied value) and a second conversion to process pages "n" through the end of the document. The second conversion will only occur when content that has not been converted is requested. This should allow the first "n" pages to be created and delivered to the Viewer without forcing the entire document to be converted.

documentSource

String

This property tells PrizmDoc Server how it should expect to get the source document for a viewing session. The following values are supported:

  • "api" means that the document will be sent to PrizmDoc Server using the PUT HTTP request. This is the default and will be used if this property is null or empty.
  • "http" means that PrizmDoc Server should download the source document from the URL provided in the "externalId" property.
  • "file" means that PrizmDoc Server should create a copy of the source document from the local file path provided in the "externalId" property.

See the How to Transfer Your Document to PrizmDoc Server topic for more details.              

documentExtension

String

Defines the extension of the document specified in the externalId property. The Requirement of this property depends on whether Format Detection is enabled (default) or disabled.

If Format Detection is disabled, then this property is only required if documentSource is "http" or "file" and the file name specified in externalId does not contain a valid document extension. If the file name specified inexternalId contains a valid extension for the document, this property can be left unset.

If Format Detection is enabled (default), then this property is optional with the following restrictions:

  • If the file is uniquely identified by the Format Detection process and no documentExtension is provided, the detected documentExtension will be used. 
  • If the file is uniquely identified by the Format Detection process and a documentExtension is provided but differs from the detected documentExtension, the detected documentExtension will be used. 
If the file is not identified by the Format Detection process and a documentExtension is provided, the provided documentExtension will be used.

The preceding "." should NOT be included in the extension value, otherwise an exception will be thrown and return 500 status from the POST HTTP request.

startConverting

String

This property determines when the process to generate pages for viewing is started. This property requires that documentSource is "http" or "file" and contentType is set to a valid value. Valid values are:

  • "initialPages" means the process to generate pages for viewing is started during the initial POST /ViewingSession request.
  • "none" means the process to generate pages for viewing is started later during a request to POST /ViewingSession/{id}/Notification/SessionStarted, GET /Page or GET /PageAttributes, whichever comes first.

contentType

String

Determines the kind of content we will start pre-generating in the background so that it is ready for request more quickly. In many cases, this property is optional (though it is required if documentSource is "http" or "file" and startConverting is "initialPages").

Note that setting this property does not set the default content type for future requests for page content, nor does it limit in any way the types of content you may request. It is only a hint so that we can begin to prepare the kind of content you will likely soon request.

Valid values are:

  • "png"
  • "svg" - paths only, no inline font (not supported in IE8)
  • "svga" - paths optimized with an inline font (not supported in IE8, IE10)
  • "svgb" - paths further optimized with an inline font (not supported in IE8, IE9, IE10, desktop Safari 9.x or Chrome on Windows)
serverSideSearch String

This property determines whether server-side text searching will be available for a document.

Valid values are:

  • "disabled" - server-side search will not be available for the viewing session.
  • "enabled" - server-side search will be available for the viewing session. (default)

When enabled at viewing session creation, large document text retrieval and server-side searching via the search task API will be available. If disabled, requests to the search task API will result in an error.

See the Search Tasks topic for more details.
minSecondsAvailable Integer

This optional property defines the amount of time in seconds for the viewingSession being created to be kept alive. The value is applicable only to viewing sessions created with the POST /ViewingSession request. A value of zero means the configured viewing session timeout value is used. The default viewingSession timeout is 20m (1200 seconds). This property is validated against the value set for viewing.sessionConstraints.minSecondsAvailable.max in the central configuration file.

When the serverCaching property is set to "full" and this property is provided, it must be 0 or a validation error will result. When the serverCaching property is set to "none" this property may be any positive integer up to viewing.sessionContraints.minSecondsAvailable.max. If the value is less than the default viewing.sessionLifetime it will be set to the default viewing.sessionLifetime (20m).
watermarks Array The array of objects which describe the watermarks to apply to the viewing session. This object is optional. The presence of valid watermark objects enables watermarking for the viewing session.
watermarks[n].type String

This property determines the type of watermark this object defines. The value of this property will determine what remaining properties are important according to the type.

Valid values:

  • "text" means that the current watermark object defines a watermark that will display horizontal text on all pages in the viewing session.
  • "diagonalText" means that the current watermark object defines a watermark that will display diagonal text on all pages in the viewing session.
  • "image" means that the current watermark object defines a watermark that will display an image on all pages in the viewing session.
Default value: N/A, this property is required.
watermarks[n].opacity Number

This property determines how transparent or opaque a watermark appears over the page content. A value of 0.0 is completely transparent (not visible). A value of 1.0 is completely opaque.

Valid values: 0.0 to 1.0

Default value: 1.0
watermarks[n].text String

This property determines the text string that will be displayed for "text" and "diagonalText" watermark types. This should not be set for "image" watermark types.

Valid values: Any valid text string

Default value: N/A, this property is required when type is "text" or "diagonalText".

See the How to Watermark Content in a Viewing Session topic for more information about special properties of the text string.
watermarks[n].color String

This property determines the color of the text that will be displayed for "text" and "diagonalText" watermark types. This should not be set for "image" watermark types.

Valid values: Any valid CSS color name (i.e. "red", "darkblue") or HEX value ("#FF0000")

Default value: "black"
watermarks[n].fontFamily String

This property determines the font name of the text that will be displayed for "text" and "diagonalText" watermark types. This should not be set for "image" watermark types.

Valid values; Any valid font family name

Default: Browser default font

See the How to Watermark Content in a Viewing Session topic for more information about the use of fonts.
watermarks[n].fontSize String

This property determines the font size of the text that will be displayed for "text" and "diagonalText" watermark types. This should not be set for "image" watermark types.

Valid values: A string containing a positive, non-zero decimal number followed by "pt" (i.e. "27.5pt").

Default value: "12pt"
watermarks[n].fontStyle String

This property determines the style of the text that will be displayed for "text" and "diagonalText" watermark types. This should not be set for "image" watermark types.

Valid values:

  • "normal" means that the  text will have no additional styling applied.
  • "italic" means that the text will be italicized.

Default value: "normal"
watermarks[n].fontWeight String

This property determines the weight of the text that will be displayed for "text" and "diagonalText" watermark types. This should not be set for "image" watermark types.

Valid Values:

  • "normal" means that the  text will be a normal weight.
  • "bold" means that the text will be bold weight.
Default value: "normal"
watermarks[n].textDecoration String

This property determines the decoration applied to the text that will be displayed for "text" and "diagonalText" watermark types. This should not be set for "image" watermark types.

Valid Values:

  • "none" means that the  text will have no additional decoration.
  • "underlined" means that the text will be underlined.
Default value: "none"
watermarks[n].horizontalAlign String

This property determines the horizontal alignment within the page for "text" and "image" watermark types. This property does not apply to "diagonalText" watermarks. For "left" and "right" values, sensible margins will be used so that the edge of the watermark does not fall on the very edge of the page.

Valid Values:

  • "left" means that the  watermark will be aligned on the left side of the page. Further, multi-line text watermarks will also have left alignment.
  • "center" means that the  watermark will be aligned on the center of the page. Further, multi-line text watermarks will also have center alignment.
  • "right" means that the  watermark will be aligned on the right side of the page. Further, multi-line text watermarks will also have right alignment.

Default value: "center"
watermarks[n].verticalAlign String

This property determines the vertical alignment within the page for "text" and "image" watermark types. This property does not apply to "diagonalText" watermarks. For "top" and "bottom" values, sensible margins will be used so that the edge of the watermark does not fall on the very edge of the page.

Valid Values:

  • "top" means that the  watermark will be aligned on the top of the page.
  • "middle" means that the  watermark will be aligned on the middle of the page.
  • "bottom" means that the  watermark will be aligned on the bottom of the page.

Default value: "middle"
watermarks[n].slope String

This property determines the angle that the text is drawn for "diagonalText" watermark types. This should not be set for "image" and "text" watermark types.

Valid Values:

  • "up" means that the  diagonal text will start in the lower-left corner of the page and extend to the upper-right corner of the page.
  • "down" means that the  diagonal text will start in the upper-left corner of the page and extend to the lower-right corner of the page.
Default value: "up"
watermarks[n].autoSize String

This property determines how an "image" watermark type will be sized to fill a page. If specified, any values for scale, verticalAlign, and horizontalAlign will be ignored. Note that the sensible automatic margins mentioned above for verticalAlign and horizontalAlign do not apply when auto-sizing an image watermark. In this case, the image should reach the very edge of the page. This should not be set for "text" and "diagonalText" watermark types.

Valid Values:

  • "fit" means the image is scaled as far as possible while maintaining aspect ratio and without allowing any of the image to go beyond the edge of the page.
  • "fill" means the image is scaled so that it completely fills the entire page with aspect ratio maintained. Some of the image may fall off the edge of the page, but the entire page is guaranteed to be covered by some part of the image.
  • "stretch" means the image is resized to be the same as the page. Aspect ratio is ignored.

Default value: N/A, the scale, verticalAlign, and horizontalAlign properties will be used if unset.
watermarks[n].scale Number

This property determines the size of images that are located using the verticalAlign and/or horizontalAlign properties. A scale value may be specified as a numeric value between 0.0 and 1.0. The value 1.0 indicates the image will be scaled to the size of the page and 0.0 indicates the image will be scaled infinitesimally small and will not be rendered. This should not be set for "text" and "diagonalText" watermark types.

Valid values: 0.0 to 1.0

Default value: 0.25 as long as autoSize is not set.
watermarks[n].src String

This property determines the source of the image data for "image" watermark types. This should not be set for "text" and "diagonalText" watermark types.

Note: The image watermark source must be a PNG. If other image formats are provided it will cause invalid watermarks to be created.

Valid values:

  • A work file ID referencing a valid work file. See the Work File topic for more information about creating work files and obtaining their IDs.
  • A URL specifying an absolute location with an HTTP or HTTPS scheme. This URL must be accessible from the server hosting the PrizmDoc RESTful Web Services.
Default value: N/A, required for "image" watermark types.
pageContentEncryption String

Allows content encryption to be enabled or disabled for a single viewing session, overriding the PrizmDoc Server configuration on the server. See the "viewing.contentEncryption.enabled" setting in the Central Configuration Options topic for more details about enabling or disabling content encryption on the server. 

Valid values for this property are:

  • "enabled" means that the server will encrypt page content in the responses for the current viewing session. This value will override the PrizmDoc Server configuration setting.
  • "disabled" means that the server will NOT encrypt page content in the responses for the current viewing session. This value will override the PrizmDoc Server configuration setting.
  • "default" means that the PrizmDoc Server configuration setting will be used to determine whether or not it encrypts page content in the responses for the current viewing session. This is the default behavior.

Setting this property to null or not including it at all means the same as "default".

See the topic Enabling Content Encryption for more information about this feature.

 Additionally, the server configuration setting "viewing.sessionConstraints.pageContentEncryption.allowedValues" can be used to limit the values of this property that the server will accept. A value outside of the acceptable values defined by this server configuration setting will cause an error and the viewing session will not be created. See the "viewing.sessionConstraints.pageContentEncryption.allowedValues" setting in the Central Configuration Options topic for more details about defining allowable values for this property.    

Response Body

If successful, this method returns the following properties:

Property Name

Value

Description

viewingSessionId

String

The ID for this new viewing session.
affinityToken String The affinity token associated with this new viewing session, if PrizmDoc is running in Multi-Server Mode.

Example
Copy Code 
POST http://localhost:18681/PCCIS/V1/ViewingSession

Example
Copy Code 
POST http://localhost:18681/PCCIS/V1/ViewingSession
Content-Type: application/json
{
    "tenantId": "my application name",
    "externalId": "my-unique-document-name.docx",
    "render": {
        "html5": {
            "alwaysUseRaster": false
        }
    },
    "minSecondsAvailable": 1500,
    "watermarks": [
        {
            "type": "text",
            "opacity": 0.6,
            "text": "jdoe\n67.79.169.114\n11/13/2014 2:24 PM\NOT FOR DISTRIBUTION",
            "color": "red",
            "fontFamily": "Consolas",
            "fontSize": "16pt",
            "fontWeight": "bold",
            "verticalAlign": "bottom",
            "horizontalAlign": "right"
        }
    ]
}

 

Example Successful Response
Copy Code 
{
    "viewingSessionId":"8091681f-15bf-4150-94a0-3ff7f2acd42d"
    "affinityToken":" S2ZqtGi9vUAXBgdmM/PNNpCM4CApe9NxLIp/4QnAHlg="
}

 

Examples of Errors Related to the minSecondsAvailable Property

Scenario when central configuration file contains: viewing.sessionConstraints.minSecondsAvalable.max: 1500 

Example
Copy Code 
POST http://localhost:18681/PCCIS/V1/ViewingSession
Content-Type: application/json
{
    "tenantId": "my application name",
    "externalId": "my-unique-document-name.docx",
    "minSecondsAvailable": 3500
}

 

Example Error Response
Copy Code 
HTTP 480 InvalidInput
{
 "errorCode": "InvalidInput".
 "errorDetails": {
      "in": "body",
      "at": "minSecondsAvailable",
      "expected": {
           "type": "integer",
           "greaterThanOrEqualTo":0,
           "lessThanOrEqualTo": 1500
       }
   }
}

 

Scenario when serverCaching is set to "full": viewing.sessionConstraints.minSecondsAvalable.max: 1500

Example
Copy Code 
POST http://localhost:18681/PCCIS/V1/ViewingSession
Content-Type: application/json
{
     "tenantId": "my application name",
     "externalId": "my-unique-document-name.docx",
     "minSecondsAvailable": 500,
     "serverCaching": "full"
}

 

Example Error Response
Copy Code 
HTTP 480 InputNotSupportedWithServerCachingEnabled
{
  "errorCode": "InputNotSupportedWithServerCachingEnabled".
  "errorDetails": {
       "in": "body",
       "at": "minSecondsAvailable",
  }
}

 

DELETE ViewingSession/u{ViewingSessionID}

This RESTful API requests the PrizmDoc Server service to delete the viewing session.

Http Method

DELETE

Resource URL

/PCCIS/V1/ViewingSession/u{ViewingSessionID}

Parameters

ViewingSessionID The ID of the viewing session associated with the request.

Request Body

None.

Example
Copy Code 
DELETE http://localhost:18681/PCCIS/V1/ViewingSession/u8091681f-15bf-4150-94a0-3ff7f2acd42d

Response

When a DELETE request is made for a viewing session with serverCaching set to "none".

Example
Copy Code 
HTTP 204

When a DELETE request is made for a viewing session which does not exist.

Example
Copy Code 
HTTP 404

When a DELETE request is made for a viewing session with serverCaching set to "full".

Example
Copy Code 
HTTP 580
Content-Type: application/json
{
     "errorCode": "CannotDeleteCachedViewingSession"
}

 

PUT ViewingSession/u{ViewingSessionID}/SourceFile?FileExtension={FileExtension}

A document source is uploaded to the PrizmDoc Server by writing the contents into the request stream using the viewing session ID from the previous viewing session ID request. 

Http Method

PUT

Resource URL

/PCCIS/V1/ViewingSession/u{ViewingSessionID}/SourceFile?FileExtension={FileExtension}

Parameters

ViewingSessionID

The ID of the viewing session associated with the request.

FileExtension

This is the file extension of the document being uploaded. This parameter may or may not be required depending on the file type and whether Format Detection is enabled. Note that the extension must not include the leading period (for example, 'jpg' is accepted but '.jpg' will return a 400 HTTP status). Extensions are not case sensitive. If Format Detection is disabled, the FileExtension must be provided. 

If Format Detection is enabled (default), the use of the FileExtension is as follows:

  • If the file is uniquely identified by the Format Detection process and no FileExtension is provided, the detected FileExtension will be used.
  • If the file is uniquely identified by the Format Detection process and a FileExtension is provided but differs from the detected FileExtension, the detected FileExtension will be used.   
  • If the file is not identified by the Format Detection process and a FileExtension is provided, the provided FileExtension will be used.
  • If the file is not identified by the Format Detection process and no FileExtension is provided, an error code of 'UnrecognizedFileFormat' will be returned with a HTTP 580 status.

Request Body

In the request body, supply the document data to be uploaded.

Response Body

Empty.

Example
Copy Code 
PUT http://localhost:18681/PCCIS/V1/ViewingSession/u8091681f-15bf-4150-94a0-3ff7f2acd42d/SourceFile?FileExtension=doc

 

Example Response
Copy Code 
Empty

GET ViewingSession/u{ViewingSessionID}/SourceFile{?ContentDispositionFilename}

Returns the original source document for a valid, active viewing session. The document returned will be an identical copy of the document originally provided to PCCIS; no conversions to other formats are supported.

The response will set the Content-Type header value to the registered MIME type associated with document extension of the original document. If a registered MIME type is not found, the value "application/octet-stream" is used. 

Http Method

GET

Resource URL

/PCCIS/V1/ViewingSession/u{ViewingSessionID}/SourceFile

Parameters

Name Description Details
ViewingSessionID ID of the viewing session.

string, required

Example:

uW1ZpNTSfU139Zh3dfdhwbff
ContentDispositionFilename

Name to use for the filename attribute in the Content-Disposition response header.

The default value is "file-{WorkFileId}.{extension}".

The file extension of the source file will automatically be added to the Content-Disposition filename.

string, optional

Example:

MonthlySalesReport

Request Body

None

Response Body

The document data, in its original format.

Example
Copy Code 
GET http://localhost:18681/PCCIS/V1/ViewingSession/u8091681f-15bf-4150-94a0-3ff7f2acd42d/SourceFile

Example Response
Copy Code 
200 OK
Content-Type: application/msword
Content-Disposition: attachment; filename=MontlySalesReport.pdf
[Document Data]

POST ViewingSession/u{ViewingSessionID}/Notification/SessionStarted

This RESTful API requests the PrizmDoc Server service to begin conversion of the document to HTML format. The object property, viewer, will be set to "HTML5". 

The User-Agent header should be set to an appropriate browser string to enable the PrizmDoc Server to begin generating the correct content for the Viewer.

Http Method

POST

Resource URL

/PCCIS/V1/ViewingSession/u{ViewingSessionID}/Notification/SessionStarted

Parameters

ViewingSessionID

The ID of the viewing session associated with the request.

Request Body

In the request body, supply an object with the following optional property:

Property Name

Value

Description

viewer

String

Specify the type of viewer being used. The only supported value is "HTML5".

The default value is "HTML5".

Response Body

Empty.

Example
Copy Code 
POST http://localhost:18681/PCCIS/V1/ViewingSession/u8091681f-15bf-4150-94a0-3ff7f2acd42d/Notification/SessionStarted

 

Example Response
Copy Code 
Empty

POST ViewingSession/u{ViewingSessionID}/Notification/SessionStopped

This request is used to stop, or invalidate, an active viewing session. This can be useful in situations when a viewing session is started but something prevents the document from being uploaded to the PrizmDoc RESTful Web Services successfully. You may also have a need in your application to stop a viewing session after a user is done with it and before the viewing session expires.

The parameters provided in the body of the request should be set with some consideration within your application. The httpStatus and endUserMessage property values specified in the body of this request will determine the HTTP status code and reason phrase that will be returned in the response for any request of the viewing session once this request has been issued.

For example, if this request is sent with httpStatus = 504 and endUserMessage = "Session is no longer available" and then a request is made to get page 0 for the same viewing session, the response status of that request will be 504 Session is no longer available and the page content will not be delivered.

This allows you to explicitly handle the error case when requests are sent after the session has been stopped. 

Http Method

POST

Resource URL

/PCCIS/V1/ViewingSession/u{ViewingSessionID}/Notification/SessionStopped

Parameters

ViewingSessionID

The ID of the viewing session associated with the request.

Request Body

In the request body, optionally supply a SessionStoppedProperties resource with the following optional properties:

Property Name Value Description
endUserMessage String A message suitable for display to the end user to be returned if any attempt to use the session is made after the session has been stopped. Default is "Session is stopped".
httpStatus Integer The http status suitable for display to the end user to be returned if any attempt to use the session is made after the session has been stopped. Default is 580.
accusoftErrorNumber Integer A custom Accusoft error number that should be sent back to the end user to be returned if any attempt to use the session is made after the session has been stopped. Default is 580.
serverLogMessage String A message that should be placed into the server's log file when the session is stopped. Default is "The viewing session is stopped on request from the client".

Response Body

Empty.

Example
Copy Code 
POST http://localhost:18681/PCCIS/V1/ViewingSession/u8091681f-15bf-4150-94a0-3ff7f2acd42d/Notification/SessionStopped
{
  "endUserMessage": "Session no longer available",
  "httpStatus": 504,
}

 

Example Response
Copy Code 
200 OK

PUT /PCCIS/V1/ViewingSession/u{id}/SourceRef

Assigns an existing work file to be used as the source document for this viewing session. This can be particularly useful when you want to avoid repeatedly uploading the same source file to the back end.

Request

Query Parameters

None

Request Headers

None

Request Body

A JSON object specifying a refType of "workFile" and the file id of the work file to use. 

Name

Description

Details

refType

Must be set to "workFile".

string, required

fileId

The id of the work file to use as a source document.

string, required
Example
Copy Code 
{
      "refType": "workFile",
      "fileId": "mUiXiqsQuevJKO9Swa32Bd"
}

Successful Response

HTTP Status Code

200

Response Headers

None

Response Body

Empty

Error Response: Work file not found

If the work file you specified has expired or does not exist, you will receive an HTTP 480 response with a JSON object containing an errorCode of "NotFound".

HTTP Status Code

480

Response Headers 

Name

Description

Content-Type

Will be set to "application/json".

Response Body

Example
Copy Code 
HTTP 480
Content-Type: application/json
{
     "errorCode": "NotFound",
     "errorDetails": {
         "in": "body",
         "at": "fileId"
     }
}

Error Response: Cannot change document once set

Once a viewing session is given a source document, that document cannot be changed. If a viewing session already has a source document and you attempt to assign a document by reference, you will receive an HTTP 480 error response with an errorCode of "CannotChangeDocument":

Example
Copy Code 
HTTP 480
Content-Type: application/json
{
     "errorCode": "CannotChangeDocument",
     "errorDetails": {
         "in": "body",
         "at": "fileId"
     }
}

 

GET /PCCIS/V1/ViewingSession/u{id}/FileId

Returns the id of the work file which is being used for this viewing session. 

Regardless of how a source document is provided, whether it is uploaded directly or whether an existing work file is used by reference, once the viewing engine has acquired the source document it will first ensure that a copy of it is present in the work file system.

Getting the work file id for a viewing session can be particularly helpful if you have uploaded a file directly to a viewing session and then want to reuse that file for a new viewing session without uploading it again.

Request

Query Parameters

None

Request Headers

None

Response

HTTP Status Codes

200

480 - When a document has not been provided yet.

Response Headers

Name

Description

Content-Type

Will be set to "application/json".

Response Body

When a source document exists:

As long as this viewing session has a source document, the response will contain a work file id:

Example
Copy Code 
HTTP 200
Content-Type: application/json
{
      "fileId": "mUiXiqsQuevJKO9Swa32Bd"
}

When a source document has not been provided:

If you just created a viewing session and have not yet provided a source document (either by upload or reference), then this URL will respond with:

Example
Copy Code 
HTTP 480
Content-Type: application/json
{
      "errorCode": "DocumentNotProvidedYet",
      "errorDetails": {
          "in": "body",
          "at": "fileId"
      }
}

 

 

 

©2017. Accusoft Corporation. All Rights Reserved.

Send Feedback